home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 001 / upgrade2 / !ChangeFSI / FSIinfo < prev    next >
Text File  |  1993-11-24  |  53KB  |  991 lines
  1.      ChangeFSI: Colour Image Processing Using the 256 colour modes
  2.  
  3. Archimedes computers have full colour display capabilities built into them as
  4. standard. However, compared with the hardware found in larger workstations, the
  5. facilities provided have been carefully reduced (in order to make them cheap
  6. enough to fit all the time). So the precision of the digital to analogue
  7. converters is only 4 bits (instead of 8) and the colour palette only has 16
  8. entries (instead of 256).
  9.  
  10. The VIDC 256 colour mode
  11. =========================
  12.  
  13. Has 4 direct bits (top 2 green, top red and blue) plus 4 palette look up bits
  14. which affect the remaining DAC bits. This therefore gives a choice of 256
  15. colours from 4096, but the choice is not a free one in that the 4 direct bits
  16. are always connected: this leaves only 256 selections available from the 4096
  17. colour range. To repeat: there are 256 simultaneous colours in a selection out
  18. of 4096 colours, where there are only 256 "legal" selections. The new VIDC20
  19. allows an arbitrary selection of colours, but the default situation is
  20. identical.
  21.  
  22. There are "optimal" selections. An optimal selection is one which covers the
  23. entire R, G, B colour cube (i.e. 0-fullscale for each of the colours) and can
  24. thus be dithered to from any picture (if one considers picture's colour range
  25. as an arbitrary volume in the colour cube, then you can dither/display a
  26. picture accurately if and only if the volume covered by the available colours
  27. encloses the picture's). The optimal selection used for the RISC OS 256 colour
  28. mode palette contains 2 most significant bits of Red, 2 most significant bits
  29. of Green and 2 most significant bits of Blue, with the last 2 bits controlling
  30. the 2 least significant bits in parallel ("adds white" to a colour). Thus peak
  31. R, G, B is obtained (without side effects if varied simultaneously, with a side
  32. effect if peak R (say) alone is required). A correctly designed error diffusion
  33. dither algorithm can display pictures with very high fidelity. [note that
  34. dithering all pictures with a single palette permits their display
  35. simultaneously on the screen, also note that dithering to a fixed palette is
  36. much quicker than selecting a palette first!]
  37.  
  38. One can also program the system for a large number of n bits per colour modes,
  39. with the n bits starting at the most significant end of the colour range. For
  40. example 4 bits of green, 3 bits of red and 1 bit of blue. The constraints are:
  41.      2 <= nGreen <= 4
  42.      1 <= nRed   <= 4
  43.      1 <= nBlue  <= 4
  44.      (and nRed+nBlue+nGreen=8)
  45. Modes like these are often useful for real time solid modelling (where the
  46. expense of dithering with error diffusion (circa 100 cycles per pixel) cannot
  47. be afforded). These selections are non-optimal: the colour cube is not
  48. completely spanned.
  49.  
  50. Displaying A Picture
  51. ====================
  52.  
  53. Since a colour in the 256 colour mode can be such a complicated thing, with
  54. varying capability of spanning the colour cube and an unknown accuracy, there
  55. is a RISC OS standard way of specifying a colour you wish to draw with using 8
  56. bits for R, G and B components. A call to the operating system converts this to
  57. the nearest colour and new objects can be drawn.
  58.  
  59. Where the object to be drawn is a previously generated picture, the modules
  60. "SpriteExtend" (in the ROM) and "ColourTrans" (in the !System directory) in
  61. RISC OS provide some capabilites for displaying pictures in different screen
  62. modes. ColourTrans can look at the palette which a sprite uses and return a
  63. list of the equivalent 'closest' colours in the current screen mode.
  64. SpriteExtend can paint sprites using the list of equivalent colours and can
  65. change the size of the image into the bargain. This is all very well for simple
  66. pictures or pictures created directly for a particular mode, but what happens
  67. for more detailed information or pictures from other sources with resolution
  68. not matched by the Archimedes hardware?
  69.  
  70. Also the above facilities are rather basic: ColourTrans makes no effort to use
  71. dithering (the practise of putting patterns of different coloured pixels
  72. together to represent other colours) and SpriteExtend simply discards
  73. additional information if reducing the picture in size (and together they make
  74. no attempt to enhance the picture when making it larger). The reason for these
  75. shortcomings is quite simple: speed. The algorithm used in ChangeFSI uses 105
  76. ARM instructions per pixel - and that's apart from any instructions used to
  77. read the image in, change its size and write the result out. For comparison,
  78. the normal sprite plot takes only one instruction per pixel (4 instructions for
  79. four 8 bit pixels). Processing a MODE 15 picture thus uses up too many seconds
  80. of ARM cpu time to imagine it as part of the interactive desktop.
  81.  
  82. So what does ChangeFSI do to make the situation better? And why does it take so
  83. long? One can immediately draw up some desirable properties for any solution to
  84. the image changing problem:
  85.  
  86. (1) Maximising the volume of the colour cube. Colour represented in the Red,
  87. Green and Blue computer graphics system can be thought of as a point in a 3D
  88. cube whose axes are the red, green and blue values. Whatever clever
  89. approximations, dithering or error diffusion techniques are used, the colour
  90. volume spanned by the r, g and b axes in the target should be large enough to
  91. contain the source volume. If not, then the picture will appear faded in some
  92. way compared to the original ("the red doesn't seem quite the same"). For a
  93. single picture a colour volume only as large as the input could be chosen;
  94. alternatively for an arbitrary set of input pictures, the colour volume on the
  95. output system has to be made as large as possible. Where animation is required
  96. the colour volume has to be consistent for all the pictures. When generating
  97. the largest volume, it is important to use the system hardware to the limit:
  98. for example, if one has two bits of control over the Archimedes 4 bit D to A
  99. converters, the largest range is covered by values 0, 5, 10 and 15 (rather than
  100. 0, 4, 8 and 12).
  101.  
  102. (2) Giving hue consistency at different saturations. For example, with a
  103. palette with different numbers of bits of r, g and b it may be impossible to
  104. have a consistent set of colours representing derived colours at different
  105. levels of intensity. Shades of white and secondary colours (cyan, magenta and
  106. yellow) are particularly difficult.
  107.  
  108. (3) Working with the multi-tasking desktop. Acorn are asking for all new
  109. software to be built on the multitasking system. This implies that the palette
  110. should not be changed (or that the agreement of all programs currently running
  111. is obtained first).
  112.  
  113. The desktop (default) palette in the 256 colour modes (e.g. modes 13, 15, 21,
  114. 24 and 28) is quite well designed. It does have the properties of (1) and (2)
  115. (it even has 16 shades of grey) and automatically satisfies (3). It is used by
  116. many Acorn programs (Draw, Paint) and by external programs (Euclid, ProArtisan,
  117. Atelier, ..) to great effect and is a safe choice for ChangeFSI. There are two
  118. ways ChangeFSI can choose a colour:
  119.  
  120. (a) a method which derives values for r, g, b and tint algorithmically (no
  121. suffix) (suitable only for the default RISC OS 256 colour palette)
  122.  
  123. (b) search the palette for the closest colour (r suffix). The precise method by
  124. which this is done is the subject of another document.
  125.  
  126. ASIDE: the closest colour is chosen such that the distance between the true
  127. colour and the choice is minimised in the colour cube space. Since the human
  128. eye is more sensitive to green, then red and lastly blue, the distance function
  129. is weighted 10, 3 and 1 in green's favour.
  130.  
  131. With the 16 colour modes (e.g. modes 9, 12, 16, 20 and 27) the default palette
  132. does not satisfy (1) and (2) unless the output is purely shades of grey -
  133. ChangeFSI can use either 8 greys (for the desktop) or 16 greys (out of the
  134. desktop or with the desktop palette altered to provide 16 greys). For colour
  135. representation, ChangeFSI can either:
  136.  
  137. (a) use 1 bit of red, 1 bit of green and 1 bit of blue (i.e. the standard 8
  138. digital colours Black, Red, Green, Blue, Yellow, Magenta, Cyan and White). This
  139. spans the colour cube and is hue consistent, but doesn't use the full range of
  140. bits provided in the format. ColourTrans can map this to the desktop with the
  141. standard palette with fair success, except for the lack of magenta (full
  142. red+full blue) in the palette. A better result can be achieved by setting 6 of
  143. the colours in the palette to red, green, yellow, blue, magenta and cyan. Since
  144. ColourTrans will map the colours anyway, it doesn't matter which 6, but the
  145. most consistent values are 8=blue, 9=yellow, 10=green, 11=red, 13=cyan,
  146. 14=magenta (leaving 0-7, 12 and 15 unchanged). This option is selected by a "d"
  147. (digital RGB) suffix to the program's mode argument.
  148.  
  149. or (b) search the palette for the closest colour (r suffix) [ChangeFSI needs to
  150. be in the 16 colour mode in order to read the palette]
  151.  
  152. With the 4 colour modes (e.g. modes 8, 11, 19 and 26) ChangeFSI is really
  153. pushed. Shades of grey output is done with the 0, 5, 10, 15 level palette. But
  154. how can colour be done? For example, each pixel can display only one of (say)
  155. black, red, green or blue. This fails to span the colour cube (it does only
  156. half of it), however, so black, cyan, magenta and yellow are used instead. The
  157. rest has to be left to luck: there is no way it can approximate to pure shades
  158. of red, green or blue. 4 bit colour pictures can be seen on the desktop in 16
  159. colour modes with the above palette or in 256 colour modes. This option is by a
  160. "c" suffix. If you can provide a better palette, then ChangeFSI can use it with
  161. the "r" suffix search method.
  162.  
  163. With 2 colour modes (e.g. modes 0, 18, 23 and 25) pixels are either ON or OFF,
  164. ChangeFSI will only do shades of grey output.... However, the method used can
  165. be varied (see later).
  166.  
  167. So that's the canvas ChangeFSI has to work on. How does it display the input
  168. range of colours on these outputs? The answer is, as stated above, dithering:
  169. the process of approximating intensity variations with patterned areas. There
  170. are two basic types of dithering technique: that used to print colour magazines
  171. and newspaper photographs "clustered dot dither" - the size of the dot of ink
  172. gives the intensity; and that used on dot matrix displays, for example the grey
  173. level patterns used by 1 bit per pixel mode on the desktop "dispersed dot
  174. dither" where the average number of dots in the area gives the intensity.
  175.  
  176. Why does the world need two different techniques? Well, different devices
  177. reproduce pixels differently. The "ideal square" pixels produced by an LCD are
  178. perfect for dispersed dot dither; a CRT produces a gaussian spot (a circle or
  179. ellipse which decays in intensity towards the edges) instead of a square -
  180. dispersed dot dither works well; a dot matrix impact printer or a "write black"
  181. laser printer produce large dots (diameter at least SQR(2) over unit pixel
  182. square) and thus make pictures too dark if dispersed dot dither is used; a
  183. "write white" laser printer prints negative "white dots" on a black field and
  184. thus "caves in" the sides of pixels making pictures too white with dispersed
  185. dot dither. Clustered dot dither reduces the effects of mis-sized pixels by
  186. ensuring they are adjacent (and thus the error is confined to the periphery of
  187. the shape) but this does have a cost in poorer resolution.
  188.  
  189. Since ChangeFSI's colour or greyscale output is to CRTs (or LCDs in some
  190. distant future) it automatically uses a dispersed dot dither. Monochrome output
  191. could be for the screen or for a printer: the user can select between dispersed
  192. and clustered methods by adding a various suffices ("c", "d" or "t") to the
  193. mode number for clustered output. For "c" the algorithm (due to Robert L Gard,
  194. 1976) approximates tones in the range 0..16 (17 levels) by using 0..16 "on"
  195. pixels in a 4 by 4 cell. For "d" the algorithm (developed by me, but similar to
  196. Gard's) approximates tones in the range 0..4 (5 levels) by using 0..4 "on"
  197. pixels in a 2 by 2 cell. For "t" the algorithm (ditto as "d") approximates
  198. tones in the range 0..9 (10 levels) by using 0..9 "on" pixels in a 3 by 3 cell.
  199. The "on" pixels are carefully chosen to provide: (a) symmetry of white/black
  200. and black/white patterns (b) diagonally oriented dot grid. The diagonal angle
  201. reduces the eye's ability to see the rectangular patterns produced. The various
  202. sizes of the halftone cell allow some trade off between representing the tonal
  203. values correctly and loss of resolution. Start with "c" and progress to "t" and
  204. then "d" if the resolution is not acceptable.
  205.  
  206. ChangeFSI can generate reasonable pictures on "write black" printers with a
  207. dispersed dot dither by using the "-black" parameter; however images produced
  208. like this do not photocopy at all well (the photocopier makes the dots blacker
  209. again!). The parameter to -black (default value 32, range 0..128) tells
  210. ChangeFSI how much larger than the ideal square pixel the dots produced by the
  211. printer are - 128 corresponds to an inked dot covering four times the area of
  212. the ideal black square pixel (and this will generally mean ChangeFSI produces
  213. an entirely white output!). Values above 64 give rather poor results on some
  214. pictures but may be worth experimenting with. The default is 32, a dot covering
  215. 50% more area than the square pixel (the minimum circle enclosing the pixel
  216. square). Some printers produce dots of (pseudo-randomly) varying sizes and
  217. black correction may not help with these (the picture looks "noisy") in which
  218. case use one of the clustered output methods. -black correction makes pictures
  219. on the screen look very pale, since, if anything, black pixels on screen are
  220. smaller than the ideal square.
  221.  
  222. [aside: to print these pictures, you need a method which copies the pixels
  223. ChangeFSI has made exactly to those of the output device. Using !Paint, scale X
  224. and Y by 90:300 for a 300dpi printer.]
  225.  
  226. In all cases, an approximation to a colour will produce an error (which might
  227. possibly be zero if ChangeFSI is very lucky). ChangeFSI tracks these errors and
  228. ensures that over wide areas there is no overall error using a technique called
  229. "error diffusion", first devised by R W Floyd and L Steinberg in 1975. In this
  230. technique the approximation is made and the error distributed to nearby pixels
  231. in the following ratios:
  232.  
  233.                 current pixel   7/16 of error
  234. 3/16 of error   5/16 of error   1/16 of error
  235.  
  236. ChangeFSI gets some of its name from Floyd and Steinberg. Additionally,
  237. ChangeFSI scans through the picture in a serpentine fashion, doing a row of
  238. pixels left to right followed by the next row right to left. This reduces the
  239. probability of regular patterns which the eye is sensitive to. The final I of
  240. the name is for Integer: ChangeFSI does all its work in 32 bit fixed point
  241. integer arithmetic (with the point at bit 28) instead of floating point.
  242. Dithering can be turned off using using "Disable Dithering" on the Processing
  243. dialogue ("-nodither" on the command line) which at least allows you to see how
  244. well it does!
  245.  
  246. The conversion from one colour range to another is made at the same time as a
  247. change in size of the image. Size is changed by ratios of areas between the
  248. input and output: the total weight of r, g, and b in the source area is
  249. calculated using the fixed point arithmetic and this result is then
  250. approximated to the output using the error diffusion to preserve information
  251. (for example, consider halving in size an image with adjacent pixels of
  252. intensities 1 and 2; the output pixel needs to be value 1.5, so the 0.5 error
  253. is sent to adjacent pixels to keep the overall colour the same). The size
  254. change is expressed as a ratio of output to input (e.g. 40:20) which ChangeFSI
  255. reduces to the smallest possible terms (2:1 in this case) so that you are free
  256. to give values like 256:512 if that's what you mean! Size change is either both
  257. x and y (if one ratio is given) or separate x and y (if two ratios are given).
  258. Note that the size of a RISC OS pixel is known, so changing from (say) mode 21
  259. to (say) mode 13 does not need any additional specified scaling. The full size
  260. output for mode 21 is the reference, so scale to 640 by 512. A common scaling
  261. is to fill the output sprite with the input and an "=" parameter to x and/or y
  262. ratios will do this without ever having to know the size of the input. Simply
  263. omitting the fractional part causes ChangeFSI to put in the source size, thus
  264. giving output which is the specified number of pixels in size.
  265.  
  266. Conversion from colour to monochrome shades of grey is done with the CIE
  267. luminance weights for r, g and b (0.299, 0.587, 0.114) which is the standard
  268. conversion for broadcast television. These values can be altered using the
  269. -red, -green and -blue commands and allow different weightings for conversion
  270. to monochrome to be tried, this also allows selection of an image composed of
  271. only some of the colours (e.g. -red1 -green0 -blue0) in making a black and
  272. white image.
  273.  
  274. ChangeFSI can take any RISC OS sprites (2, 4, 16 or 256 colours). If there is a
  275. palette it will be used, otherwise the standard 2, 4, 16 and 256 colour desktop
  276. palettes are used. ChangeFSI can also read the 16bpp and 24bpp sprites which
  277. have no palettes.
  278.  
  279. ChangeFSI is both a command line driven program and a desktop application. The
  280. file !Help describes how to use the application from the desktop, if you need
  281. to use the program as a command line driven program you will need to have it in
  282. the library (or on run$path) and press f12 to get out of the desktop. The file
  283. "FSIuse" describes the parameters concisely. The program selects mode 0 when
  284. run from the command line when doing any work in order to speed up processing
  285. (this can be disabled with -nomode). It may also be a good idea to RMFaster
  286. BASIC. An hourglass %age processed figure is displayed (this may run through
  287. twice for some of the more expensive options). The program reads the source
  288. image from disc and builds the output in memory, having claimed some from the
  289. system.
  290.  
  291. In addition to strictly converting the source image, ChangeFSI can also process
  292. it. A trivial option is "-info": ChangeFSI will tell you what it is doing (a
  293. good way of finding out what the source image actually is, and how the scaling
  294. turns out!). Similarly trivial are -vflip and -hflip - the picture can be
  295. produce upside down and left/right reversed. Not so trivial is -rotate, which
  296. will rotate the image by 90 degrees (that is, an anti- clockwise quarter turn).
  297. -rotate- rotates by -90 degrees (clockwise quarter turn).
  298.  
  299. Sometimes useful is "-nosize": ChangeFSI can read pixel size information from
  300. the source image (if present) or guess it (e.g. if there are less than 320 by
  301. 256 pixels in a source image, ChangeFSI assumes the pixels are the same size as
  302. MODE 13's [45 per inch]) or derive it from other information and scale the
  303. output image (composed of RISC OS square or 1:2 sized pixels) appropriately.
  304. -nosize stops this from happening. [this seems particularly relevant on formats
  305. like TIFF or IFF where the pixel size is specified *but may be wrong*] Using
  306. -info will display the pixel ratios which ChangeFSI is using - a combination of
  307. the size guess, the output pixel size and any deliberate scaling. "-noscale"
  308. turns off the output scaling as well.
  309.  
  310. The simplest image processing option is "-range" which will expand the dynamic
  311. range of the input picture so that it fills the available area (not a good
  312. option for animated sequences unless all source images possess the same range).
  313. Since r, g, b are processed by the same amount, -range preserves the colour of
  314. pixels in coloured pictures.
  315.  
  316. A useful option for output intended for the screen only is Gamma correction.
  317. CRT displays do not have a simple linear relationship between brightness of the
  318. spot and input voltage: instead of brightness = const * voltage, the response
  319. is brightness = const * voltage ^ (1/gamma). In the TV industry, gamma has been
  320. standardised as 2.2, but there is wide variation in the computer industry: the
  321. monitor's response will vary depending on what make it is and how it is
  322. adjusted. Low values of gamma (0 to 1) make colours darker and high values
  323. (above 1) make colours lighter with the effects being particularly noticeable
  324. on dim colours. "-gamma" uses the default of 2.2, and it can be set by
  325. "-gamma1.5" say. Gamma correction is most relevant when its known that the
  326. input has a linear intensity (input from a scanner or from another computer
  327. with more bits per colour component than the Archimedes).
  328.  
  329. A more complex primitive is "-equal" which performs "histogram equalisation" on
  330. the image. This makes the histogram of level versus number of points at that
  331. level as flat as possible giving full use of the number of colours available.
  332. -equal is a very harsh primitive, even on monochrome inputs it can produce an
  333. inferior picture; while on colour pictures it can distort the colour of each
  334. point (since r, g, b are computed separately). But -equal can often recover a
  335. picture that is otherwise completely useless or expose information locked in a
  336. small part of the input scale.
  337.  
  338. Image colours may be inverted with the -invert option. Which may be fun in
  339. colour but is rarely useful! However, monochrome images frequently need
  340. inverting, especially one bit per pixel sources.
  341.  
  342. A more powerful option is "-sharpen" which enhances the edges of objects in the
  343. picture: this is very useful since the dithering process inevitably smears
  344. information over the display. Pre-sharpening the image can result in a more
  345. acceptable output. Default values of sharpening can be overridden for special
  346. effects: -sharpen8 does edge detection. Lower amounts of sharpening are
  347. obtained with larger -sharpen numbers. In general the more input and output
  348. pixels and the greater the output range in a pixel in the images, the less
  349. sharpening is required. Sharpening a picture which is already dithered can give
  350. a very bad result....
  351.  
  352. The sharpening is achieved with the following matrix:
  353.  
  354.    -1    -1    -1
  355.    -1 sharpen  -1
  356.    -1    -1    -1
  357.  
  358. ChangeFSI computes the sum of nine pixels with the above weights for each input
  359. pixel and renormalises the result (divides by sharpen-8).
  360.  
  361. An option for testing is "-nodither" which disables the Floyd Steinberg error
  362. diffusion step completely. Versions after 6th June 1990 are more accurate at
  363. doing this.
  364.  
  365. The various processes described above are applied in the following order for
  366. pictures with more output pixels than input:
  367.    (a) range or histogram equalisation,
  368.    (b) sharpen,
  369.    (c) scale,
  370.    (d) error diffusion.
  371. This order is chosen so that:
  372.    (1) since the input pixels (rather than the output pixels) are sharpened,
  373.        there is no false edge introduced when pixels are replicated.
  374.  
  375. The various processes described above are applied in the following order for
  376. pictures with fewer output pixels than input:
  377.    (a) scale,
  378.    (b) range or histogram equalisation,
  379.    (c) sharpen,
  380.    (d) error diffusion.
  381. This order is chosen so that:
  382.    (1) ranging can enhance down-sized images. Say a black/white dithered image
  383.        is reduced in size, so that the output from the scaling process is (some
  384.        approximation to) the original grey levels; then ranging can expand this
  385.        if possible.
  386.    (2) sharpening can be used to offset the blurring effects of scaling.
  387.    (3) since the output pixels (rather than the input pixels) are sharpened,
  388.        the effect of -sharpenN is consistent over differently scaled images.
  389.  
  390. There may be times when this automatic selection of order gets it wrong,
  391. particularly when changing the aspect ratio, it is possible to trigger some
  392. undesirable sharpening artifacts. Use the program twice with sharpening (say)
  393. disabled and enabled in the order required.
  394.  
  395. Examples of use:
  396.  
  397. Make "standard palette" versions of existing 256 colour images (for example
  398. the Watford digitiser plus colour board doesn't use the standard palette).
  399.   (e.g. "changefsi in out 13p" for a coloured Watford picture)
  400.  
  401. Or convert a colour picture to something you can see on your high res mono
  402. monitor.
  403.   (e.g. "changefsi in out 18 -sharpen -info")
  404.  
  405. Or convert a large monochrome picture (from a scanner, say) to something
  406. which can be seen.
  407.   (e.g. "changefsi in out 20t 1:4 -gamma")
  408.  
  409. Or convert a colour picture to grey scale for the desktop.
  410.   (e.g. "changefsi in out 20")
  411.  
  412. Or change a 512 by 480 image to standard format and aspect ratio
  413.   (e.g. "changefsi in out 15 640:512 512:480")
  414.   (or "changefsi in out = -range")
  415.  
  416. Or change to digital r, g, b
  417.   (e.g. "changefsi in out 20d -sharpen16")
  418.  
  419. Or convert a picture for printing on a 300dpi laser.
  420.   (e.g. "changefsi in out 18c 300:90 -sharpen")
  421.  
  422. And many more uses such as making miniatures of pictures, animated sequences of
  423. pictures changing size (or sharpness!), converting Artisan pictures to the
  424. desktop (try looking at the Artisan Garden with the desktop in 256 colours and
  425. ChangeFSI's version - the stripes on the lawn vanish with the standard
  426. version). Obviously you will need to have captured input as a sprite first!
  427. Using more pixels per inch can improve the quality of the result, particularly
  428. converting to multisync modes.
  429.  
  430. Note that, for all work with ChangeFSI, it is a good idea to start from the
  431. unprocessed input each time and do everything in one pass (rather than using
  432. the program several times with simple arguments). It is not a good idea to
  433. sharpen a dithered image (unless it has been shrunk).
  434.  
  435. *** It is a very good idea to keep the highest resolution master that you can
  436. afford the disc space for....
  437.  
  438. The ChangeFSI program can also convert from non RISC OS sprite formats while
  439. doing all of the above processing. ChangeFSI will work out what the format is
  440. automatically. For native RISC OS formats, it uses the filetype and there can
  441. be no confusion. For alien formats, it first tries looking for particular
  442. identifying information inside the file and then (if this fails to have
  443. identified a format) tries using the file name itself. See the details below:
  444.  
  445. The RISC OS sprite format
  446.  Contains 1, 2, 4 or 8 bits per pixel with a modification palette of up to
  447.  16 entries; any number of pixels wide and high uncompressed. Details are in
  448.  Acorn's Programmer's Reference Manual.
  449.  + Recognised by file type FF9 (a paint brush and house icon)
  450.  - Details of how many bits per pixel and the pixel size are obtained from
  451.    the operating system (rather than being in the file) from the "MODE"
  452.    number. Mode extensions can result in a source image containing a MODE
  453.    number which your computer does not understand.
  454.  - Mask information ignored
  455.  - Lefthand wastage ignored
  456.  
  457. The new RISC OS sprite format
  458.  Contains 1, 2, 4, 8, 16 or 32 bits per pixel.
  459.  + Recognised by file type FF9
  460.  + no problem with mode extensions: information is coded into the format
  461.  - Mask information ignored
  462.  
  463. Kodak PhotoCD
  464.  24 bit per pixel images at various resolutions
  465.  + Recognised by file type BE8
  466.  - Set ChangeFSI$PCDIndex to read resolutions other than base (=3)
  467.  
  468. The ArVis format [of ArVis Multimedia]
  469.  Contains 5 bits of red, green and blue information encoded into two RISC OS
  470.  sprites "HIP.<filename>" and "LOP.<filename>" comprising a 640 pixel wide
  471.  and 256 line tall image with pixels sized 1:2. Details from ArVis Multimedia
  472.  - Recognised by providing the HIP.<filename> (which must be of file type FF9)
  473.  - Uncompressed (indeed represents 16 bits instead of 15).
  474.  
  475. The Pineapple colour digitiser format (of Pineapple Software)
  476.  Contains 6 bits of green, 5 bits of red and blue information filed as a
  477.  single data file starting "FSIfile" comprising a 512 pixel wide and 256
  478.  line tall image with pixels sized 1:2.
  479.  - Recognised by "FSIfile" in the file (which can be any type)
  480.  - Uncompressed
  481.  
  482. The Watford Video Digitiser "picture" format
  483.  Contains a run length encoded 64 grey level 512 pixel wide, 256 line image,
  484.  with pixels sized 1:2. Details from Watford Electronics Ltd.
  485.  + Recognised by file type DFA (a small grey picture of Stevie Nicks)
  486.  - Warning: don't forget to save the pictures in *un-dithered* state!
  487.  When used with a colour converter, ChangeFSI can read three colour
  488.  separations stored in a directory of separate "red", "green" and "blue"
  489.  files. Beware of auto-gain/contrast when using such information!
  490.  
  491. The ProArtisan compressed picture file format
  492.  Contains a (mildly) compressed MODE 15 (640 by 256 by 256 colours) picture.
  493.  Details from Clares.
  494.  + Recognised by file type DE2 (a beige monitor in a grey surround)
  495.  
  496. The TimeStep satellite image format
  497.  This gives an uncompressed 800 by 800 with 256 grey levels.
  498.  + Recognised by file type 7A0 (icon never seen)
  499.  - No resolution specified, equal to mode 27 assumed
  500.  - Documentation never seen. An extra header file <name>! is not understood
  501.    at all.....
  502.  
  503. CCIR601 4:2:2 images
  504.  Contain 720 pixels by 288 rows (PAL) [243 rows NTSC] YUV coded with
  505.  pixels sized 1:2.
  506.  + Recognised by file type 601
  507.  - one field only
  508.  
  509. Another TimeStep satellite image format
  510.  Giving an uncompressed 128 pixels wide by 256 lines with 256 grey levels,
  511.  pixels sized 2:1. Used by TimeStep's !ImProcess application.
  512.  + Recognised by file type 300 ("i" in a document frame)
  513.  - Documentation never seen.
  514.  - A bit coarse
  515.  The grey levels represent intensity in various different wave bands. By
  516.  naming files "red", "green" and "blue" and handing ChangeFSI the directory,
  517.  you can produce a false colour image. Hours of experimentation can produce
  518.  an almost reasonable picture...
  519.  
  520. The AIM and Wild Vision V10 format
  521.  This provides an uncompressed 256 by 256 image with 256 grey levels. Details
  522.  from Delft University of Technology and ECD Computers Delft B.V.
  523.  + Recognised by file type 004 (a picture of 'Trui' with "TU" in blue)
  524.  + ChangeFSI can write to this format (specify "aim" in the mode position)
  525.    and specify = in the sizing to get a 256 by 256 output (otherwise it will
  526.    be the same size as the source image)
  527.  - No resolution specified, equal to mode 27 assumed
  528.  - The associated file <name>+ (file type 010) which contains additional
  529.    information is ignored by ChangeFSI.
  530.  The grey levels may represent intensity in various different wave bands. By
  531.  naming files "red", "green" and "blue" and handing ChangeFSI the directory,
  532.  you can produce a false colour image. Hours of experimentation can produce
  533.  an almost reasonable picture...
  534.  
  535. The Wild Vision V12 format
  536.  This provides an uncompressed 512 by 512 image with 256 grey levels.
  537.  + Recognised by file type 006
  538.  - No resolution specified, equal to mode 27 assumed
  539.  
  540. The Wild Vision V9 and SnapShot formats
  541.  This provides an uncompressed 512 by 256 image with 4 bits of red, green
  542.  and blue, pixels sized 1:2.
  543.  + Recognised by "MercSoft" or "SnapShot" header
  544.  + No file type needed
  545.  
  546. The !Translator Clear format
  547.  This provides 1, 2, 4, 8 and 24 bits per pixel.
  548.  + Recognised by file type 690
  549.  - uncompressed, especially for <8 bits per pixel which is recorded at one
  550.    byte per pixel.
  551.  - No resolution specified, equal to mode 27 assumed
  552.  
  553. The Atari ST "Degas" format
  554.  1, 2 or 4 bits per pixel, clear or run length encoded. RISC OS file type by
  555.  John Kortink of !Translator.
  556.  + Recognised by file type 691
  557.  - No documentation and only 5 images read
  558.  - No resolution specified, equal to mode 27 assumed
  559.  
  560. >> All the file formats so far have been designed on RISC OS (or Arthur) and
  561. recognition of the format is defined by file type, the files arrive on RISC
  562. OS floppy discs, and the originators live in the same time zone. For the
  563. following formats many of these things are not true... Which makes it more
  564. difficult to guarantee that ChangeFSI will be able to read the file.
  565.  
  566. The Millipede Prisma format (used by CadSoft also)
  567.  The Millipede Prisma 3 is a 768 pixels wide by 574 line interlaced display
  568.  board for the Archimedes and BBC Microcomputer. It allows use of 256
  569.  colours from 2^24. Files may be stored uncompressed (432KBytes!) or run
  570.  length encoded. More details from CadSoft or Millipede Electronic Graphics.
  571.  + Recognised by "MILLIPEDE" at offset 16 in the file
  572.  - No resolution specified, equal to mode 27 assumed
  573.  - slowish to read the compressed formats
  574.  - scaling the picture using = can be poor since 574 lines don't relate very
  575.    well to 512 or 256. Use -info to display the scale ratios.
  576.  
  577. The Aldus/MicroSoft TIFF format (also filetype FF0 is assigned to TIFF)
  578.  Frequently used by scanners, TIFF is a common interchange format for
  579.  graphics images on the Mac and PC (particularly DTP and Windows). It
  580.  provides an arbitrary number of bits per pixel, size etc using a numeric tag
  581.  scheme allowing new information to be introduced without upsetting existing
  582.  programs. The format may be compressed (in 5 different ways at present).
  583.  Details from Aldus UK, MicroSoft, Hewlett Packard...
  584.  + Recognised by file type FF0
  585.  + Recognised by "II" plus the 16 bit number 42 at the start of the file for
  586.    little endian machines (ix86, ARM, VAX...)
  587.  + Recognised by "MM" plus the 16 bit number 42 at the start of the file for
  588.    big endian machines (M680x0...)
  589.  + Can read PackBits images and LZW compressed forms (at least the 3 its
  590.    seen so far...)
  591.  - Cannot read predictor compressed LZW images.
  592.  - So far ChangeFSI has only done 1, 4, 8 and 24 bit images.
  593.    It can't read "planar" images or CCITT compressed forms.
  594.  - Some TIFF images have incorrect pixel sizes: use -nosize if this is
  595.    true. If no pixel size is specified, ChangeFSI assumes mode 27 size.
  596.  + TIFF is a trademark of Aldus Corporation
  597.  
  598. The CompuServe GIF format
  599.  Used for wide area network transfer of images. It provides an LZW
  600.  compressed up to 256 colours from 2^24 arbitrary sized image. Details from
  601.  CompuServe (USA) [or usenet]
  602.  + Recognised by "GIF87a" at the start of the file
  603.  + LZW compression is efficient even for dithered images
  604.  + ChangeFSI can decompress LZW quickly
  605.  - No resolution specified, equal to mode 27 assumed
  606.  - many low quality images around from PCs
  607.  
  608. The Electronic Arts IFF ILBM format
  609.  Provides an arbitrary sized image with up to 4096 colours sometimes run
  610.  length encoded. ChangeFSI understands the generic format and also the
  611.  special Amiga format for "HAM" and "Half-bright" images.
  612.  + Recognised by "FORM" as the first four characters and "ILBM" as
  613.    characters 8 to 11
  614.  - Only pixel aspect ratio specified, not its size (and then sometimes
  615.    incorrectly): use -nosize *and* a size change (a:b) if its wrong
  616.  - images often small
  617.  - doesn't understand Amiga "hires"
  618.  - can't convert HAM pictures directly to monochrome
  619.  
  620. The MicroSoft Windows 3 .BMP format
  621.  Used by MicroSoft in Windows 3 and PaintBrush for Windows 3. Provides an
  622.  arbitrary sized image and 1, 4 or 8 bits per pixel. Uncompressed.
  623.  + Recognised by "BM" as the first two characters
  624.  - No resolution specified, equal to mode 27 assumed
  625.  - documentation never seen - 7 files examined and intelligent guesses made!
  626.  
  627. The Digital Research GEM .IMG format
  628.  Used by GEM (and GEM Paint) on both PC and Atari ST. Provides an arbitrary
  629.  sized image and number of bits per pixel (though its only usually used with
  630.  up to 5 bits per pixel) and pixel size. Compressed by run length encoding
  631.  and line repeats.
  632.  - Recognised by 00 01 00 08 as the first four bytes ("version 1, header
  633.    length 8") or by "IMG" as the name of the directory the file is in.
  634.  - Planar file format slow to read
  635.  - Palette not specified: ChangeFSI assumes linear shades of grey. You might
  636.    need to use -invert if the image is a negative
  637.  - The size of a pixel is specified in microns. The standard RISC OS 90
  638.    pixels per inch translates to (1/90*2.54*10,000) microns - 282. (use
  639.    -info to get information about the scaling, -nosize to stop it)
  640.  - Documentation from the "ST World" magazine's clinic.
  641.  
  642. An unknown PC .PIC format
  643.  Used for some VGA demos, the format provides an uncompressed 320 by 200 by
  644.  256 colour (from 2^24) VGA screen dump.
  645.  + Recognised by "AV_VO" as the first five bytes in the file
  646.  - Documentation never seen
  647.  - Pixel size assumed the same as MODE 13 (45 pixels per inch).
  648.  
  649. The MacPaint format
  650.  Provides a 576 by 720 bitmap, run length coded by the Mac's "PackBits"
  651.  algorithm (repeated bytes).
  652.  - Recognised by "PNTG" at position 65 in the file. This may only relate to
  653.    files which have been through a program called "MacFix". Data assumed to
  654.    start at position 128 in the file. Header ignored.
  655.  - No resolution specified, equal to mode 25 assumed
  656.  
  657. The Mac PICT2 format (PICT extended version 2)
  658.  Provides an arbitary size packed picture, run length coded by the Mac's
  659.  "PackBits" algorithm (repeated bytes).
  660.  + Recognised by looking for the PICT header at position 514 in the file.
  661.    The header is 00 11 02 FF 0C 00 FF FE.
  662.  - Documentation available but mostly useless (it assumes you are about to
  663.    call QuickDraw routines - "Note: for maximum safety and convenience, let
  664.    QuickDraw generate and interpret your pictures." Apple fail to describe
  665.    the PackBits algorithm in Inside Mac...)
  666.  - PICT is the loose equivalent of RISC OS Draw file format, but without
  667.    the explicit sizing of objects - for PICT, if there is an object that
  668.    you don't understand, there's no way of skipping it (whereas for Draw,
  669.    the size of the object is specified in an object indep. way). Apple
  670.    present a large table of the sizes of the objects (0000 - FFFF) which is
  671.    not in ChangeFSI. Consequently, if ChangeFSI finds an object it doesn't
  672.    know about before the picture, it stops...
  673.  - Only PackBitsRect (0098) (8bpp) and DirectBitsRect (009A) (24/32 bpp) are
  674.    allowed.
  675.  + ChangeFSI tries to skip a Clip (0001) region if it encounters it, since it
  676.    is hard to get the Mac OS to make PICT files without a clip opcode in them.
  677.  + size of pixel specified.
  678.  - Only 3 pictures read - since the format is very complicated (e.g. the size
  679.    of things change if >250 rows in the picture!) this is no guarentee that
  680.    anything else will be right.
  681.  
  682. The ZSoft .PCX format
  683.  Used by PC Paintbrush. Usually a 4 bit per pixel image (CGA, EGA, VGA) but
  684.  can be 1-8 bits per pixel.
  685.  - Recognised by 10,[0,2,3,4,5],1 at start of file. Or by name PCX.<foo>. Or
  686.    by type &697.
  687.  + Intelligent check for resolution of the DACs on the PC card. Use -info to
  688.    find out what ChangeFSI thinks it is.
  689.  + Pixel size information read. You may need to stop the scaling with
  690.    -nosize, since its often wrong.
  691.  
  692. The RIX Softworks ColoRIX format
  693.  Used by VGA Paint, image extension .SCE .. .SCX. 4 or 8 bits per pixel.
  694.  - Recognised by "RIX3" at start of file
  695.  - Documentation never seen
  696.  - Only 5 files read: ChangeFSI checks to see if the header is the same
  697.    as these files and complains otherwise.
  698.  - No resolution specified, equal to mode 27 assumed
  699.  
  700. The Sun "pixrect" format
  701.  Used under SunOS and also under X11. Commonly 1 or 8 bits per pixel, but up
  702.  to 24 bits per pixel can be found (see the Sun NeWS release tape!).
  703.  + Recognised by &59A55A95 at the start of the file.
  704.  - No resolution specified, equal to mode 27 assumed
  705.  - Sun didn't specify the pixel ordering of 24 bit per pixel images: many
  706.    assume RGB when it was actually BGR. Change byte &17 in the Sun
  707.    rasterfile between 1 and 3 if you have a problem.
  708.  
  709. The "pbm" 'portable bitmap' file format
  710.  Used by the "PBM-PLUS" toolkit (mainly Unix) by Jef Poskanzer. 1-24 bits
  711.  per pixel (more can be specified in the format but ChangeFSI cannot read
  712.  them). ChangeFSI can only read the "RAWBITS" formats (it can write all of
  713.  the pbm formats).
  714.  + Recognised by P4/P5/P6 at start of file.
  715.  + Writable by ChangeFSI
  716.  - No resolution specified, equal to mode 27 assumed
  717.  
  718. The UNIX "rle" format
  719.  Used by a program called "svfb" to save the contents of large frame
  720.  buffers, checked with four images at 24 bits per pixel.
  721.  + Recognised by &CC52 at the start of the file.
  722.  - No resolution specified, equal to mode 27 assumed
  723.  
  724. The TrueVision Targa format
  725.  Used by TrueVision for Vista boards. Up to 32 bits per pixel.
  726.  - Recognised by suffix _TGA or _VDA on the name. Or by type &69d.
  727.  - Only uncompressed formats readable.
  728.  - Only 8 and 16 bit per pixel formats tested.
  729.  
  730. The "Flexible Image Transport System" (FITS) format
  731.  Used for astronomical data. Up to 16 bits per pixel component.
  732.  + Recognised by "SIMPLE" at the start of the file.
  733.  - Only 8 and 16 bit per pixel component formats tested.
  734.  - Only two files ever seen!
  735.  - No resolution specified, equal to mode 27 assumed
  736.  
  737. The Irlam instruments colour scanner format
  738.  24 bit per pixel from colour scanner.
  739.  + Recognised by Irlam 24 at the start of the file.
  740.  + Writable by ChangeFSI
  741.  - No resolution specified, equal to mode 27 assumed
  742.  - may need gamma correction
  743.  
  744. The Irlam instruments YUV 411 colour video format
  745.  7 bits Y, up to 7 bits U and V.
  746.  + Recognised by Irlam YUV 411 at the start of the file
  747.  - no resolution specified, equal to mode 27 assumed
  748.  
  749. The JPEG 'JFIF' File Interchange Format
  750.  Up to 24 bits R,G,B, compressed by the JPEG compression system.
  751.  + Recognised by JFIF at position 6 in the file (you may have to
  752.    cut headers off files, particularly if they are from Macs).
  753.  + Often highly compressed
  754.  + If ChangeFSI$Cache is large enough (bigger than the file), then high
  755.    speed routines are used to decompress. Otherwise:
  756.  - ChangeFSI calls a djpeg routine. This can be on the Run$Path, implemented
  757.    as an Alias (in which case it *must* use WimpTask to start) or found
  758.    inside ChangeFSI$Dir if all else fails. cjpeg (the compressor) is also
  759.    available inside ChangeFSI$Dir - you will need to convert the image to
  760.    P6 format before it can be compressed. Djpeg and cjpeg are by the
  761.    PD JPEG group.
  762.  - ... and therefore slow. Needs a lot of space in <Wimp$Scrap>.
  763.  - no resolution specified, equal to mode 27 assumed
  764.  
  765. >> The following file formats are only recognised by their names.
  766.  
  767. An unknown PC .DSP format
  768.  Experimentally determined that it holds a 640 by 350 EGA picture at 4 bits
  769.  per pixel. ChangeFSI "knows" the default EGA palette (from IBM literature).
  770.  - Recognised by being in a directory "DSP"
  771.  - Documentation never seen
  772.  - No resolution specified, equal to mode 27 assumed
  773.  - Only two examples read(!)
  774.  
  775. The QRT .raw format
  776.  Output from Steve Koren's public domain ray tracer: arbitrary size in 2^24
  777.  colours, uncompressed. Documentation part of QRT.
  778.  - Recognised by the name ending ".Raw". Or by type &698.
  779.  - No resolution specified, equal to mode 27 assumed
  780.  
  781. The MTV pic. format
  782.  Output from Mark Terrence VandeWettering public domain ray tracer arbitrary
  783.  size in 2^24 colours, uncompressed. Documentation part of MTV. Also used by
  784.  "RayShade".
  785.  - Recognised by being in a directory "Pic.". Or by type &699.
  786.  - No resolution specified, equal to mode 27 assumed
  787.  
  788. The RT image. format
  789.  Output from "RT", a private ray tracer by Brian D Watt(?) arbitrary size in
  790.  2^24 colours, run length encoded.
  791.  - Recognised by being in a directory "Image."
  792.  - No resolution specified, equal to mode 27 assumed
  793.  
  794. For many of these formats, especially the uncompressed ones, setting the
  795. variable "ChangeFSI$Cache" to the number of bytes of temporary memory you
  796. wish the program to use will speed up reading the information. The default
  797. is 49152 bytes. For example "*set ChangeFSI$Cache 80k". For those worried
  798. about speed, the program will go faster if:
  799.  
  800.  - you use -noscale and keep 1:1 ratios (don't specify them)
  801.    (although -nosize and 1:1 or 1:2 ratios are quick, too)
  802.  - you don't need sharpening, histogram equalisation, range expansion
  803.  - you use monochrome (e.g. 25, 26, 27 and 27t) modes
  804.  
  805. additionally you can disable dithering (-nodither) especially when reading
  806. monochrome source.
  807.  
  808. You can avoid the program changing mode by putting -nomode on the command line.
  809.  
  810. Very large output files can be built strips at a time and sent directly to disk
  811. using the parameter "-max" e.g:
  812.  
  813.   ChangeFSI <in> <out> 28 -max512K
  814.  
  815. will convert the file with a maximum of 512KBytes held in memory. Options 25t,
  816. -rotate and -vflip don't work when this is being done.
  817.  
  818. Work will be done on other formats when and if both image and documentation
  819. arrive on my desk. Adding a new format is a matter of (a) putting in automatic
  820. recognition of the format at the start of the program (b) reading the size of
  821. the image and the colour palette mapping [in the next section of the program]
  822. (c) writing a "read pixel row" element inside PROCiprow (d) providing an entry
  823. in PROCrewind. If you write a new format interface, please send it to me so
  824. that it will be included in later versions. ChangeFSI has already got code for
  825. dealing with images with 1, 2, 4 and 8 bits per pixel packed into bytes and for
  826. images with up to 8 bit planes. There is support code for LZW decompression and
  827. LZW decoding.
  828.  
  829. As a special feature, ChangeFSI will also write out 256 grey level files (alter
  830. rwt, gwt and bwt to get 256 level colour separations) in AIM format. This is
  831. file type 4 with bytes representing the grey level. Use the = operation to
  832. restrict the picture to 256x256y, otherwise it will be the same size as the
  833. input. Specify "aim" as the mode string to do this.
  834.  
  835. For portability to other machines, ChangeFSI can write out files in "pbm"
  836. format. There are 3 types of format "black/white" (pbm), "grey" (pgm) and
  837. "colour" (ppm) with pure ASCII and binary encodings of each:
  838.  
  839. ASCII                                   Binary
  840. p1        "black/white" (like mode 18)  p4 (big endian bytes!)
  841. p2        "grey" (like mode 20t)        p5
  842. p3        "true colour"                 p6
  843.  
  844. Files can be read with Jef Poskanzer's portable toolkit on other machines. The
  845. p2 format is easily convertible by programmers; it consists of:
  846.  
  847. P2
  848. # comment line
  849. xsize ysize
  850. maximum_value
  851. pixel_value <whitespace> pixel_value
  852.  
  853. where all the numbers are in decimal (ASCII). 0 means black, maximum_value (=
  854. 15) means white. The p3 format is similar with r, g, b triples for each pixel
  855. value. The number of bits per component (default 8) can be set from the command
  856. line with, for example, "p3,4" for 4 bits per component.
  857.  
  858. As a special packed output format, "P15" has been implemented. Output is binary
  859. pixel values, 5 bits per component, little endian RGB order packed into 16
  860. bits. Header information as the other p formats.
  861.  
  862. Files can be written as new RISC OS sprites using S16 and S32 as the formats.
  863. The x and y pixels per inch are given as a comma seperated list - a 16 bit mode
  864. 12 equivalent is S16,90,45 while a 32 bit mode 28 equivalent is S32,90,90.
  865.  
  866. ChangeFSI can write Irlam format images (somewhat slower than p6 images...).
  867.  
  868.                               Output summary
  869.                               ==============
  870.  
  871. # cols   Colour Cube  Bits used  Consistent Hue  Desktop Palette  Mode&Suffix
  872.  
  873. 2^24            Y         24           Y             -            S32, p3 or p6 or Irlam
  874. 2^21            Y         21           Y             -            p6,7
  875. 2^18            Y         18           Y             -            p6,6
  876. 2^15            Y         15           Y             -            S16, p15 or p6,5
  877. 2^12            Y         12           Y             -            p6,4
  878. 512             Y          9           Y             -            p6,3
  879. 256 grey        n          8           Y             -            aim
  880. 256 grey        n          8           Y             -            28d
  881. 256             Y          8           Y             Y            28
  882. 256             Y          8           Y             Y            28r
  883. 16 grey         n          4           Y             n            27t
  884. 16 grey         n          4           Y             n            p2 or p5
  885. 8 grey          n          3           Y             Y            27
  886. 16              ?          4           ?             Y            27r
  887. 16              Y          3           Y           can be         27d
  888. 4 grey          n          2           Y             Y            26
  889. 4               n          2           n             n            26c
  890. 4               n          2           n             n            26r
  891. 2 (black/white) n          1           Y             Y            25
  892. 2 (black/white) n          1           Y             Y            25c/d/t
  893. 2 (black/white) n          1           Y             Y            p1 or p4
  894.  
  895.  
  896. ChangeFSI can be used from both the desktop front end and from the command
  897. line. It can also be used as a BASIC library function:
  898. LIBRARY"<ChangeFSI$Dir>.ChangeFSI" gives a new function, FNChangeFSI to the
  899. BASIC programmer. This function takes:
  900.   A$: a command line argument
  901.   spritearea%: an address or -1 for the spritearea built by ChangeFSI
  902.   workspace%: an address or -1 for ChangeFSI's other workspace
  903.   worklimit%: an address (unused if workspace%<0)
  904.   fast%: TRUE for MODE 0 selection
  905. It produces an error (to whatever error handler is present) if it fails. If
  906. spritearea% is <0 it will save the sprite to the file given in the command
  907. string, otherwise it won't. The function FNChangeFSIVersion returns the version
  908. string of the library (in the info box of the desktop application).
  909.  
  910.                            Command Summary
  911.                            ===============
  912.  
  913. -info     give details
  914.  
  915. -hist     don't process image, but display histogram of it instead
  916.  
  917. -hflip    horizontally flip the image
  918. -vflip    vertically flip the image
  919. -rotate   rotate the image by +90 degrees (i.e. anti-clockwise)
  920. -rotate-  rotate the image by -90 degrees (i.e. clockwise)
  921. -max      set the maximum size of the image before disc is used
  922.  
  923. -noscale  disable automatic pixel size correction
  924. -nosize   disable automatic pixel size correction for input pixels only
  925. -nodither disable dithering
  926. -nomode   don't change to mode 0 while processing the picture
  927. -invert   invert colour range of image
  928.  
  929. -range    expand input's dynamic range to full scale
  930. -equal    histogram equalisation
  931. -sharpen  digitally sharpen the picture
  932.  
  933. -gamma    set gamma correction
  934. -black    correct for black ink spot size
  935. -red      change red weight for deriving monochrome luminance
  936. -green    change green weight for deriving monochrome luminance
  937. -blue     change blue weight for deriving monochrome luminance
  938.  
  939. -brighten horrendous hack to slightly brighten images: may convert hues
  940.           close to white to white. (It causes the output range 0..15 to
  941.           be considered as 0..(15/16) instead of 0..(15/15)).
  942.  
  943.                            Mode Suffixes
  944.                            =============
  945.  
  946. c
  947.   1 bit modes: use clustered dithering with 4x4 cell
  948.   2 bit modes: use the four colours "black", "cyan", "magenta" and "yellow"
  949. d
  950.   1 bit modes: use clustered dithering with 2x2 cell
  951.   4 bit modes: use 1 bit red, 1 bit green, 1 bit blue
  952.   8 bit modes: use 256 level grey scale
  953. t
  954.   1 bit modes: use clustered dithering with 3x3 cell
  955.   4 bit modes: 16 level grey scale
  956. r
  957.   2 bit modes: Roger Wilson's (me) colour matching algorithm
  958.   4 bit modes: Roger Wilson's (me) colour matching algorithm
  959.   8 bit modes: Roger Wilson's (me) colour matching algorithm
  960. -no suffix-
  961.   1 bit modes: b/w dispersed dot dithering
  962.   2 bit modes: 4 level grey scale
  963.   4 bit modes: 8 level grey scale
  964.   8 bit modes: John Bowler's colour matching algorithm
  965.                (defaults to 'r' mode if not VIDC1 compatible)
  966.  
  967. Colour matching is done in r, g, b space: the minimum distance between colours
  968. is the square root of:
  969.    delta_r^2*rmatchwt+delta_g^2*gmatchwt+delta_b^2*bmatchwt
  970. ChangeFSI has hard wired weights of 3, 10, 1 respectively for its colour
  971. matching algorithms. John Bowler's algorithm (default for RISC OS 8 bit modes)
  972. although somewhat slower, is fast enough to have replaced all the previous
  973. methods [ASIDE it gives pictures at least as good as "p" mode in pre Aug 91
  974. ChangeFSI's]. Roger Wilson's (i.e. my) colour matching algorithm is
  975. recommended, and is used automatically if the 8 bit per pixel mode does not
  976. have the default RISC OS colour set.
  977.  
  978. [NOTE: thanks are due to Steve Green and the BBC and Irlam Instruments for the
  979. intermediate systems that led to John Bowler's and my algorithms: until Aug 91
  980. ChangeFSI used their work for its "Precise Matching" algorithm. It no longer
  981. uses any of their code, but owes a debt for overall approach. A small thank you
  982. to Spencer Thomas for putting me on the track which led to my colour matching
  983. system's algorithm.]
  984.  
  985. Further information on dithering can be found in "Digital Halftoning" by Robert
  986. Ulichney published by the MIT Press, ISBN 0-262-21009-6. A book which I wish
  987. I'd had when I started writing the program, rather than after it was nearly
  988. finished! Histogram equalisation is in "Algorithms for Graphics and Image
  989. Processing" by Theo Pavlidis published by Computer Science Press, ISBN
  990. 0-914894-65-X.
  991.